Release 10.1A: OpenEdge Development:
Programming Interfaces

Creating and maintaining a cryptography policy

The Progress 4GL allows you to establish a consistent set of defaults for handling cryptography in an application using the SECURITY-POLICY system handle. These cryptography settings apply globally for the duration of a 4GL session. Table 2–12 lists the attributes that you can read and set for this system handle. These attributes are both readable and setable unless otherwise indicated.

Table 2–12: SECURITY-POLICY system handle attributes

Attribute	Description
ENCRYPTION-SALT	A RAW value used together with a simple password to generate a more random and unique password-based encryption (PBE) key (default: none). For any value that you set, only the first 8 bytes are used, and values with fewer than 8 bytes are padded with zeroes. Note: Typically, you never need to set this value, and then only if the security specification for your application requires it.
PBE-HASH-ALGORITHM	A CHARACTER value that specifies the hashing algorithm to use for generating a PBE key, which you can specify as "MD5" or "SHA-1" (default: "SHA-1"). Note: Typically, you never need to set this value, and then only if the security specification for your application requires it.
PBE-KEY-ROUNDS	A positive INTEGER value that specifies the number of algorithm iterations to use for PBE key generation (default: 1000). Note: Extremely large values for this setting can significantly degrade performance. Typically, you never need to set this value, and then only if the security specification for your application requires it.
SYMMETRIC-ENCRYPTION-ALGORITHM	A CHARACTER value that specifies a supported algorithm, mode, and key size used by the 4GL symmetric encryption and decryption facilities. It must be one of the comma-separated values from the SYMMETRIC-SUPPORT attribute (default: "AES_CBC_128").
SYMMETRIC-ENCRYPTION-KEY	A write-only RAW value that specifies the symmetric key to use for encryption and decryption (default: none).
SYMMETRIC-ENCRYPTION-IV	A RAW value used together with the symmetric encryption key to provide a more random data encryption (default: none). Note: Typically, you never need to set this value, and then only if the security specification for your application requires it.
SYMMETRIC-SUPPORT	A read-only CHARACTER value that contains a comma-separated list of supported values for the SYMMETRIC-ENCRYPTION-ALGORITHM attribute setting.

For information on OpenEdge-supported defaults and options for setting these attributes, see the OpenEdge Development: Progress 4GL Reference .

Caution: In general, you must manage the values that you set for a cryptography policy in a safe manner, including generation, storage, and transport. Improper management of these values can result in loss of data.

Setting a symmetric encryption algorithm

The encryption algorithm setting determines how the 4GL encryption and decryption functions (see the "Implementing symmetric cryptography in the 4GL" section) work to protect data confidentiality in your application. This setting is actually a combination of three elements expressed in the following form:

Syntax

AAA_MMM_n

These three elements specify:

AAA

An alpha or alphanumeric abbreviation for the algorithm.

MMM

An alpha abbreviation for the mode to use.

n

A numeric value for the key size to use.

The OpenEdge default setting for the SYMMETRIC-ENCRYPTION-ALGORITHM attribute is "AES_CBC_128", which means the AES algorithm in CBC mode using a 128-bit key. The combination of algorithm, mode, and key size determines the strength and speed of the encryption. You can accept the OpenEdge default or choose a different setting, depending on your application requirements. Any setting you choose for the SYMMETRIC-ENCRYPTION-ALGORITHM attribute is used by each instance of a 4GL encryption/decryption function unless you specify an override for that function.

For more information on encryption algorithms, modes, and cryptographic keys, see the sections on cryptography in OpenEdge Getting Started: Core Business Services .

Setting an encryption key

You can set the SYMMETRIC-ENCRYPTION-KEY attribute to any RAW, MEMPTR, CHARACTER, or LONGCHAR value that conforms to the specified key size of your algorithm setting. A RAW or MEMPTR value specifies a raw binary value for the key. A CHARACTER or LONGCHAR value creates a PBE, PKC#5-compliant, binary key with a default salt value.

Caution: Note that the result of setting the SYMMETRIC-ENCRYPTION-KEY attribute is unreadable to prevent it against access by memory scanners and debuggers. You must ensure that any source for this value is overwritten in memory, or otherwise protected from unauthorized access.

The 4GL also provides a number of facilities for generating symmetric keys of various types. For more information, see the "Generating encryption keys" section.